home *** CD-ROM | disk | FTP | other *** search
/ Atari Mega Archive 1 / Atari Mega Archive - Volume 1.iso / program / funnel.zoo / sources / list.h < prev    next >
Encoding:
C/C++ Source or Header  |  1993-04-11  |  12.0 KB  |  208 lines
  1. /*##############################################################################
  2.  
  3. FUNNNELWEB COPYRIGHT
  4. ====================
  5. FunnelWeb is a literate-programming macro preprocessor.
  6.  
  7. Copyright (C) 1992 Ross N. Williams.
  8.  
  9.    Ross N. Williams
  10.    ross@spam.adelaide.edu.au
  11.    16 Lerwick Avenue, Hazelwood Park 5066, Australia.
  12.  
  13. This program is free software; you can redistribute it and/or modify
  14. it under the terms of Version 2 of the GNU General Public License as
  15. published by the Free Software Foundation.
  16.  
  17. This program is distributed WITHOUT ANY WARRANTY; without even the implied
  18. warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
  19. See Version 2 of the GNU General Public License for more details.
  20.  
  21. You should have received a copy of Version 2 of the GNU General Public
  22. License along with this program. If not, you can FTP the license from
  23. prep.ai.mit.edu/pub/gnu/COPYING-2 or write to the Free Software
  24. Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  25.  
  26. Section 2a of the license requires that all changes to this file be
  27. recorded prominently in this file. Please record all changes here.
  28.  
  29. Programmers:
  30.    RNW  Ross N. Williams  ross@spam.adelaide.edu.au
  31.  
  32. Changes:
  33.    07-May-1992  RNW  Program prepared for release under GNU GPL V2.
  34.  
  35. ##############################################################################*/
  36.  
  37.  
  38. /******************************************************************************/
  39. /*                                  LIST.H                                    */
  40. /******************************************************************************/
  41. /*                                                                            */
  42. /* Introduction                                                               */
  43. /* ------------                                                               */
  44. /* This list package (list.h and list.c) implements a list abstraction.       */
  45. /*                                                                            */
  46. /* Facts about Lists                                                          */
  47. /* -----------------                                                          */
  48. /* - A LIST stores zero or more LIST ELEMENTS.                                */
  49. /* - The user decides the type of element to be stored in each list.          */
  50. /* - Each list stores only one type of list element; lists are homogeneous.   */
  51. /* - Lists store copies of elements rather than pointers to elements.         */
  52. /* - Each list can hold from zero to about 2^31 elements.                     */
  53. /* - Each list has a HEAD end and a TAIL end.                                 */
  54. /* - Elements can be appended and deleted only at the tail of the list.       */
  55. /* - The elements of a list can be read sequentially from head to tail.       */
  56. /* - A MARKER stores the current position in the list for sequential reading. */
  57. /* - Upon list creation, the marker is positioned at the tail of the list.    */
  58. /* - In a list of n elements, elements are numbered from 1 to n.              */
  59. /* - Element 1 is at the head of the list. Element n is at the tail.          */
  60. /* - The identifier "ls" is used as an abbreviation for "list".               */
  61. /* - The identifier "el" is used as an abbreviation for "element".            */
  62. /* - Longer names are desirable, but shorter ones have been used so as to     */
  63. /*   enhance the portability of the package.                                  */
  64. /* - IMPORTANT: Lists get all their memory using mm_temp calls.               */
  65. /*                                                                            */
  66. /* How To Use This List Package                                               */
  67. /* ----------------------------                                               */
  68. /* 1. Include this .H file in your program file.                              */
  69. /* 2. Identify the type of elements to be placed in the list.                 */
  70. /* 3. Define a variable of type p_ls as a view to a list.                     */
  71. /* 4. Use the ls_* functions to perform the desired operations.               */
  72. /*    Start with a call to ls_cre and (optionally) end with a call to ls_des. */
  73. /*                                                                            */
  74. /******************************************************************************/
  75.  
  76. /* Ensure that the body of this header file is included at most once.         */
  77. #ifndef DONE_LIST
  78. #define DONE_LIST
  79.  
  80. /******************************************************************************/
  81.  
  82. #include "style.h"
  83.  
  84. /******************************************************************************/
  85.  
  86. /* Users manipulate lists through pointers to lists (p_ls_t). The following   */
  87. /* declaration serves the list user of the package while hiding the           */
  88. /* implementation details (which appear in a similar declaration in list.c).  */
  89. /* The #ifndef stops list.c from seeing these public declarations.            */
  90. #ifndef INLISTC
  91. typedef struct {word NEVER_USE_THIS_FIELD_UQJTKC;} ls_yqwx; /* Don't use! */
  92. typedef ls_yqwx *p_ls_t;
  93. typedef p_void p_lsel_t;
  94. typedef p_lsel_t *pp_lsel_t;
  95. #endif
  96.  
  97. /******************************************************************************/
  98. /*                                                                            */
  99. /* General Notes About These Functions                                        */
  100. /* -----------------------------------                                        */
  101. /* - All lists and elements are passed by pointer. Whether a parameter is     */
  102. /*   read or written is determined by it's function's description.            */
  103. /* - Each function (except ls_cre) accepts a single pointer to a list and     */
  104. /*   each function's description is assumed to be referring to the list.      */
  105. /* - "Raising an error" means calling the external function "error" to        */
  106. /*   write out a message and bomb the program.                                */
  107. /* - You must create a list using ls_cre before performing any operations     */
  108. /*   upon it. A list function will usually raise an error if it is            */
  109. /*   handed a pointer that does not point to a properly CREated list.         */
  110. /*                                                                            */
  111. /* WARNING: This package copies values into its internal data structures      */
  112. /* (through ls_add), but returns only POINTERS to elements when asked to      */
  113. /* retrieve them. These pointers are valid only so long as the element        */
  114. /* that they point to remains in the list. If the element is deleted somehow, */
  115. /* the pointer points to garbage and becomes dangerous.                       */
  116. /* So, if you have been handed a pointer to an element in a list (ls_nxt,     */
  117. /* ls_loo), do not subsequently delete the element (ls_lop, ls_emp, ls_des)   */
  118. /* and then attempt to access the element through the pointer.                */
  119. /* One sure way to avoid the problem is always to use the pointer handed back */
  120. /* by ls_nxt or ls_loo to copy the element immediately.                       */
  121.  
  122. /* The Functions                                                              */
  123. /* -------------                                                              */
  124. EXPORT p_ls_t ls_cre P_((size_t));
  125. /* CREate. Creates a new list and returns a pointer to the new list. The user */
  126. /* must specify in the parameter the size of elements that are to be stored   */
  127. /* in the list. Specify the size of elements in bytes (usually using sizeof). */
  128. /* The sequential reading marker is set to position n+1=1=tail of the list.   */
  129.  
  130. EXPORT void ls_add P_((p_ls_t,p_lsel_t));
  131. /* ADD. Adds a new element onto the tail of the list (at position n+1).       */
  132. /* The user must supply in the second parameter a pointer to the element to   */
  133. /* be added. ls_add takes a copy of the element (it knows from the earlier    */
  134. /* call to ls_cre how many bytes to copy) and stores the copy in its own      */
  135. /* internal data structures.                                                  */
  136.  
  137. EXPORT void ls_lop P_((p_ls_t));
  138. /* LOP. Removes (lops) element n from the tail of the list.                   */
  139. /* Raises an error if the list is empty.                                      */
  140.  
  141. EXPORT ulong ls_len P_((p_ls_t));
  142. /* LENgth. Returns the number of elements in the list (n).                    */
  143.  
  144. EXPORT void ls_fir P_((p_ls_t));
  145. /* FIRst. Sets the sequential reading marker to element 1.                    */
  146. /* If the list is empty (n=0) the marker is placed at the tail of the list    */
  147. /* and subsequent calls to ls_add will leave it there until the next call to  */
  148. /* ls_fir.                                                                    */
  149.  
  150. EXPORT void ls_nxt P_((p_ls_t,pp_lsel_t));
  151. /* NeXT. Returns the list element under the marker and advances the marker    */
  152. /* one position towards the tail of the list.                                 */
  153. /* The method of returning the list element is a little messy. The user       */
  154. /* supplies a pointer to a pointer in the second parameter, and the function  */
  155. /* writes the address of the element in the list into the pointer.            */
  156. /* If the marker is at position n+1 upon entry to ls_nxt, the marker position */
  157. /* doesn't change and NULL is written to the argument pointer.                */
  158.  
  159. EXPORT void ls_loo P_((p_ls_t,ulong,pp_lsel_t));
  160. /* LOOkup. Returns (using the same mechanism as ls_nxt) the k'th element of   */
  161. /* the specified list where k is the second (ulong) parameter and the first   */
  162. /* element (at the head of the list) is numbered number one (1).              */
  163. /* Raises an error if the index k is out of the range [1,n].                  */
  164.  
  165. EXPORT void ls_tai P_((p_ls_t,pp_lsel_t));
  166. /* Lookup TAIl. Returns (using the same mechanism as ls_nxt) the tail element */
  167. /* of the specified list.                                                     */
  168. /* Raises an error if the list is empty.                                      */
  169.  
  170. EXPORT void ls_emp P_((p_ls_t));
  171. /* EMPty. Empties the specified list, deallocating all the space used by the  */
  172. /* list elements. Upon completion, the list will be empty and the list marker */
  173. /* will be positioned at the tail of the list.                                */
  174.  
  175. EXPORT void ls_des P_((p_ls_t));
  176. /* DEStroy. Destroys a list, destroying all its elements and deallocating all */
  177. /* the memory used by the list.                                               */
  178.  
  179. /* Marker Functions */
  180. /* ---------------- */
  181. /* The following two functions ls_mar and ls_set were hacked in to this list  */
  182. /* package when it was discovered that the tangler sometimes needs to run     */
  183. /* more than one context down a list at the same time. The two new functions  */
  184. /* allow the list package user to save and restore the current mark.          */
  185. /* These functions are not tightly controlled and so care must be taken in    */
  186. /* their use.                                                                 */
  187.  
  188. EXPORT p_void ls_mar P_((p_ls_t));
  189. /* Returns a representation of the current list marker. */
  190.  
  191. EXPORT void ls_set P_((p_ls_t,p_void));
  192. /* Sets the position of the marker to an earlier saved position.              */
  193. /* Calls to this function should satisfy the following conditions:            */
  194. /*    1. The marker argument (p_void) must be the result of an earlier call   */
  195. /*       to ls_mar with the same list as an argument.                         */
  196. /*    2. No part of the list should have been modified in the interim. In     */
  197. /*       particular, this means that no calls to ls_add, ls_lop, ls_emp or    */
  198. /*       ls_des can be made between linked calls to ls_mar and ls_set.        */
  199.  
  200. /******************************************************************************/
  201.  
  202. /* For #ifndef preventing multiple inclusion of the body of this header file. */
  203. #endif
  204.  
  205. /******************************************************************************/
  206. /*                               End of LIST.H                                */
  207. /******************************************************************************/
  208.